
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
	
namespace Swaf
{
	/// <summary> Defines an interface for holding onto the results of calling one or more 
	/// business rules through the rule manager.</summary>
	/// <remarks>
	/// This class is capable of managing rule call results and any failure info
	/// that might have occured during the call.  When calling the rule manager
	/// with multiple rules at once, the results returned is a collection, with
	/// <code>numberOfResults()</code> matching the number of rules called at one time.
	/// <p>
	/// Use <code>getExceptionInfo()</code> or <code>getExceptionInfo(index)</code> to assertain
	/// whether a business rule call failed for some reason before getting the results
	/// of the business rule.</p></remarks>
	/// <author>Matthew Denman</author>
	public interface IResults
	{
		/// <summary> Returns the first result from calling a business rule.
		/// When calling the rule manager for a single rule call, there will only
		/// be one result in the object, and calling <code>getCallResults()</code> will
		/// return the results from the business rule.</summary>
		/// <remarks>
		/// When calling the rule manager with multiple rules in one call, there will
		/// be multiple results in this object and calling <code>getCallResults()</code>
		/// will return the first rule's results.  Use <code>getCallResults(index)</code>
		/// to get the results of other rules called in the one call to the rule
		/// manager.</remarks>
		/// <returns>an Object that is the return value from making the business rule call.
		/// This could be null if the rule's return value is void or if the call to 
		/// the business rule failed.  On failure <code>getExceptionInfo</code> should return
		/// the Exception object that caused the failure.
		/// </returns>
		object CallResults {get;}

		/// <summary>
		/// Returns the specified results from the collection of results contained
		/// within this object.</summary>
		/// <remarks>
		/// When calling the rule manager with multiple rules in one call, this
		/// method will allow access to the results of each rule that was executed
		/// by the rule manager.  Use <code>numberOfResults()</code> to loop through the
		/// results of the calls.</remarks>
		/// <param name="index">Specifies the specific business rule call results desired.  This
		/// value should be within the range of &gt;= 0 through to &lt; <code>numberOfResults</code>
		/// </param>
		/// <returns>an Object that is the return value from making the business rule call
		/// on the specific index provided.
		/// This could be null if the rule's return value is void or if the call to
		/// the business rule failed.  On failure <code>getExceptionInfo(index)</code>
		/// should return the Exception object that caused the failure.
		/// </returns>
		object getCallResults(int index);

		/// <summary>
		/// Returns the first Exception object from calling a business rule.</summary>
		/// <seealso cref="IResults.getCallResults(int)">
		/// for more information regarding the semantics of getting results.</seealso>
		/// <returns>
		/// The first Exception object or null if the call to the rule was successful.</returns>
		Exception ExceptionInfo {get;}

		/// <summary>
		/// Returns the specified Exception object from the collection of results contained
		/// within this object.</summary>
		/// <seealso cref="IResults.ExceptionInofgetCallResults()
		/// "/>
		/// <param name="index">The index into the collection of results contained within this object.
		/// Should be >= 0 through < <code>numberOfResults()</code>.
		/// </param>
		/// <returns>The Exception object or null if the rule call was successful.
		/// 
		/// </returns>
		Exception getExceptionInfo(int index);

		/// <summary>Returns the number of results contained within this object.  The number returned
		/// should match the number of business rules called in one call to the rule
		/// manager.
		/// </summary>
		/// <returns>The number of results in this object.
		/// 
		/// </returns>
		int numberOfResults{get;}

		string getXml();
	}
}